home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Fmt.man < prev    next >
Encoding:
Text File  |  1990-05-30  |  13.0 KB  |  399 lines
  1.  
  2.  
  3.  
  4. Fmt                   C Library Procedures                    Fmt
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Fmt_Convert - Package for converting  data  from  one  byte-
  12.      order/alignment format to another.
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ffmmtt..hh>>
  16.  
  17.      int
  18.      FFmmtt__CCoonnvveerrtt(_c_o_n_t_e_n_t_s, _i_n_F_o_r_m_a_t, _i_n_S_i_z_e_P_t_r, _i_n_B_u_f_f_e_r, _o_u_t_F_o_r_m_a_t, _o_u_t_S_i_z_e_P_t_r, _o_u_t_B_u_f_f_e_r)
  19.  
  20.      int
  21.      FFmmtt__SSiizzee(_c_o_n_t_e_n_t_s, _i_n_F_o_r_m_a_t, _i_n_S_i_z_e_P_t_r, _o_u_t_F_o_r_m_a_t, _o_u_t_S_i_z_e_P_t_r)
  22.  
  23. AARRGGUUMMEENNTTSS
  24.      char         *_c_o_n_t_e_n_t_s    (in)      String  describing  con-
  25.                                          tents  of  _i_n_B_u_f_f_e_r (see
  26.                                          below).
  27.  
  28.      Fmt_Format   _i_n_F_o_r_m_a_t     (in)      Byte-order/alignment
  29.                                          format    of   data   in
  30.                                          _i_n_B_u_f_f_e_r.
  31.  
  32.      int          *_i_n_S_i_z_e_P_t_r   (in/out)  Points   to   size    of
  33.                                          _i_n_B_u_f_f_e_r.   Upon  return
  34.                                          *_i_n_S_i_z_e_P_t_r is the number
  35.                                          of bytes actually used.
  36.  
  37.      char         *_i_n_B_u_f_f_e_r    (in)      Data to be converted.
  38.  
  39.      Fmt_Format   _o_u_t_F_o_r_m_a_t    (in)      Byte-order/alignment
  40.                                          format  of  data in _o_u_t_-
  41.                                          _B_u_f_f_e_r.
  42.  
  43.      int          *_o_u_t_S_i_z_e_P_t_r  (in/out)  Points to size  of  _o_u_t_-
  44.                                          _B_u_f_f_e_r.    Upon   return
  45.                                          *_o_u_t_S_i_z_e_P_t_r contains the
  46.                                          number of bytes actually
  47.                                          used. For FFmmtt__SSiizzee  this
  48.                                          is   strictly   an   out
  49.                                          parameter.
  50.  
  51.      char         *_o_u_t_B_u_f_f_e_r   (in)      Converted data.
  52.  
  53. _________________________________________________________________
  54.  
  55.  
  56. DDEESSCCRRIIPPTTIIOONN
  57.      FFmmtt__CCoonnvveerrtt   converts   data   between   different    byte-
  58.      order/alignment formats. Typically this is done between dif-
  59.      ferent machine types, but it can be used to convert  between
  60.      two  compilers that align data differently.  _I_n_F_o_r_m_a_t speci-
  61.      fies  the  byte-order/alignment  format  of  the   data   in
  62.  
  63.  
  64.  
  65. Sprite v.1.0         Printed:  May 29, 1990                     1
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. Fmt                   C Library Procedures                    Fmt
  73.  
  74.  
  75.  
  76.      _i_n_B_u_f_f_e_r,  and  _o_u_t_F_o_r_m_a_t specifies the byte-order/alignment
  77.      format of the data in _o_u_t_B_u_f_f_e_r after the  conversion.   The
  78.      data to be converted is read from _i_n_B_u_f_f_e_r and the converted
  79.      data is  written  to  _o_u_t_B_u_f_f_e_r.   The  parameter  _i_n_S_i_z_e_P_t_r
  80.      points  to  the  size  of the input buffer. When FFmmtt__CCoonnvveerrtt
  81.      returns *_i_n_S_i_z_e_P_t_r contains the number of  bytes  that  were
  82.      actually  used.   It  is  possible  for less than the entire
  83.      buffer to be converted depending upon the  _c_o_n_t_e_n_t_s  string.
  84.      See  below for more details on _c_o_n_t_e_n_t_s.  The parameter _o_u_t_-
  85.      _S_i_z_e_P_t_r points to  the  size  of  the  output  buffer.  When
  86.      FFmmtt__CCoonnvveerrtt returns *_o_u_t_S_i_z_e_P_t_r contains the number of bytes
  87.      actually used.
  88.  
  89.      FFmmtt__SSiizzee computes the minimum size output buffer needed con-
  90.      verting  the  data  at  described by the _c_o_n_t_e_n_t_s string The
  91.      result is returned in *_o_u_t_S_i_z_e_P_t_r.  This size  can  then  be
  92.      passed to FFmmtt__CCoonnvveerrtt (assuming that the format and contents
  93.      parameters remain the same).
  94.  
  95.      The legal values for the format parameters  are  defined  in
  96.      fmt.h.  They are as follows:
  97.  
  98.      FFMMTT__6688KK__FFOORRMMAATT
  99.           The byte-order/alignment format of code compiled by Gcc
  100.           for Motorola 680x0 machines.  Treating an integer as an
  101.           array of 4 bytes (char  buf[4]),  buf[0]  contains  the
  102.           most significant byte. Halfwords, words and doublewords
  103.           are aligned on even boundaries. The alignment of struc-
  104.           tures  and unions equals the most restrictive alignment
  105.           of one of their members, such that they  are  at  least
  106.           aligned  on  an  even boundary.  The size of structures
  107.           and unions is a multiple of their alignment.
  108.  
  109.      FFMMTT__VVAAXX__FFOORRMMAATT
  110.           The byte-order/alignment format of the  Vax.   Treating
  111.           an integer as an array of 4 bytes (char buf[4]), buf[0]
  112.           contains the  least  significant  byte.  Halfwords  are
  113.           aligned  on  even boundaries. Words and doublewords are
  114.           aligned on word boundaries. The alignment of structures
  115.           and unions equals the most restrictive alignment of one
  116.           of their members.  The size of structures and unions is
  117.           a multiple of their alignment.
  118.  
  119.      FFMMTT__SSPPUURR__FFOORRMMAATT
  120.           The byte-order/alignment format of code compiled by Gcc
  121.           for  the  Spur.   Treating  an integer as an array of 4
  122.           bytes (char buf[4]), buf[0] contains the least signifi-
  123.           cant  byte.   Halfwords are aligned on even boundaries,
  124.           words are aligned on quad boundaries,  and  doublewords
  125.           are aligned on oct boundaries.  The alignment of struc-
  126.           tures and unions equals the most restrictive  alignment
  127.           of  one  of  their members, such that they are at least
  128.  
  129.  
  130.  
  131. Sprite v.1.0         Printed:  May 29, 1990                     2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. Fmt                   C Library Procedures                    Fmt
  139.  
  140.  
  141.  
  142.           aligned on a quad boundary.  The size of structures and
  143.           unions is a multiple of their alignment.
  144.  
  145.      FFMMTT__SSPPAARRCC__FFOORRMMAATT
  146.           The byte-order/alignment format of code compiled by the
  147.           SunOS compiler for the Sparc architecture.  Treating an
  148.           integer as an array of 4 bytes  (char  buf[4]),  buf[0]
  149.           contains  the  most  significant  byte.   Halfwords are
  150.           aligned on even boundaries, words are aligned  on  quad
  151.           boundaries,  and  doublewords  are aligned on oct boun-
  152.           daries.  The alignment of structures and unions  equals
  153.           the most restrictive alignment of one of their members.
  154.           The size of structures and  unions  is  a  multiple  of
  155.           their alignment.
  156.  
  157.      FFMMTT__MMIIPPSS__FFOORRMMAATT
  158.           The byte-order/alignment format of code compiled by the
  159.           Ultrix compiler for the Mips (DecStation3100) architec-
  160.           ture.  Treating an integer as an array of 4 bytes (char
  161.           buf[4]),  buf[0]  contains  the least significant byte.
  162.           Halfwords are aligned on  even  boundaries,  words  are
  163.           aligned on quad boundaries, and doublewords are aligned
  164.           on oct boundaries.  The  alignment  of  structures  and
  165.           unions  equals the most restrictive alignment of one of
  166.           their members.  The size of structures and unions is  a
  167.           multiple of their alignment.                             |
  168.  
  169.      FFMMTT__MMYY__FFOORRMMAATT                                                      ||
  170.           This  format  is  set  to  the format of the machine on  |
  171.           which the code is running.  This relieves  the  program  |
  172.           that  is  using  the  FFmmtt package from having to decide  |
  173.           with format is appropriate for a particular machine.
  174.  
  175.      The _c_o_n_t_e_n_t_s parameter is used to describe  the  data  types
  176.      that  comprise  the  input  buffer.  The  buffer can contain
  177.      bytes, halfwords (2 bytes), words (4 bytes), doublewords  (8
  178.      bytes),  structures,  and  unions.   These  data  types  are
  179.      represented in the contents string using the following char-
  180.      acters.
  181.  
  182.      bb    One byte.
  183.  
  184.      hh    One halfword (2 bytes).
  185.  
  186.      ww    One word (4 bytes).
  187.  
  188.      dd    One double word (8 bytes).
  189.  
  190.      {{    The start of a structure.
  191.  
  192.      }}    The end of a structure.
  193.  
  194.  
  195.  
  196.  
  197. Sprite v.1.0         Printed:  May 29, 1990                     3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204. Fmt                   C Library Procedures                    Fmt
  205.  
  206.  
  207.  
  208.      ((    The start of a union. The '((' must  be  followed  by  a
  209.           discriminant  that indicates which of the components of
  210.           the union is to be converted.  The  discriminant  is  a
  211.           decimal  number  that gives the index of the component,
  212.           starting at 0.
  213.  
  214.      ))    The end of a union.
  215.  
  216.      00-99* A decimal number following a data type (byte, halfword,
  217.           word,  doubleword,  structure, or union) indicates that
  218.           the data type is repeated the given  number  of  times.
  219.           For instance, the string "w5" means that the input con-
  220.           tains 5 consecutive words. There is an  ambiguity  that
  221.           arises  when  describing  the contents of a union. "w5"
  222.           can either refer to one component of 5 words, or  to  5
  223.           components  of  one word each. The abiguity is resolved
  224.           by having "w5" refer to one component of 5  words,  and
  225.           "wwwww"  refer  to 5 components of one word. Similarly,
  226.           "w*" refers to one component (see  next  paragraph  for
  227.           description of the '*' character).
  228.  
  229.      **    A '**' means 1 or more repetitions of the previous  data
  230.           type.  The  number  of repetitions is determined by the
  231.           amount of data remaining in the input buffer. Care must
  232.           be  taken if the '**' character is anything but the last
  233.           character in the string.  Certain  formats  place  con-
  234.           straints on the sizes of unions and structures that may
  235.           cause the '**' character to give unwanted  results.  For
  236.           example, consider a structure consisting of a word fol-
  237.           lowed by a byte that is defined  as  "{wb*}".   In  the
  238.           Spur  format  "b*"  will refer to 4 bytes, while in the
  239.           68K format it will refer to 2 bytes.
  240.  
  241.  
  242.      The following are examples of input data types  and  content
  243.      strings.
  244.  
  245.      _D_a_t_a:
  246.  
  247.           int  foo[5];
  248.  
  249.      _C_o_n_t_e_n_t _s_t_r_i_n_g:
  250.  
  251.           "w5" or "w*" or "wwwww"
  252.  
  253.      _D_a_t_a:
  254.  
  255.  
  256.               struct      flea    {
  257.                   char        mite;
  258.                   int         spider;
  259.                   int         worm;
  260.  
  261.  
  262.  
  263. Sprite v.1.0         Printed:  May 29, 1990                     4
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270. Fmt                   C Library Procedures                    Fmt
  271.  
  272.  
  273.  
  274.                   short       moth;
  275.                   short       mosquito;
  276.                   short       beetle;
  277.                   int         fly[5];
  278.                   char        gnat[50];
  279.               };
  280.  
  281.      _C_o_n_t_e_n_t _s_t_r_i_n_g:
  282.  
  283.      "{bwwh3w5b*}"
  284.  
  285.      _D_a_t_a:
  286.  
  287.  
  288.               struct  foo     {
  289.                   char        bar;
  290.                   int         baz;
  291.                   union {
  292.                               short   quux;
  293.                               double  cow;
  294.                   } dog[6];
  295.               };
  296.  
  297.      _C_o_n_t_e_n_t _s_t_r_i_n_g:
  298.  
  299.          "{bw(0hd)6}" or "{bw(0hd)*}"  if "quux" is the component
  300.      of "dog" to be converted,
  301.      or,
  302.          "{bw(1hd)6}" or "{bw(1hd)*}" if "cow" is  the  component
  303.      of "dog" to be converted.
  304.  
  305.  
  306. RREETTUURRNN VVAALLUUEESS
  307.      The following return codes are defined in fmt.h:
  308.  
  309.      FFMMTT__OOKK (0)
  310.           Procedure completed properly
  311.  
  312.      FFMMTT__CCOONNTTEENNTT__EERRRROORR
  313.           The _c_o_n_t_e_n_t_s parameter contained an error.
  314.  
  315.      FFMMTT__IINNPPUUTT__TTOOOO__SSMMAALLLL
  316.           The input buffer was smaller  than  indicated  by  _c_o_n_-
  317.           _t_e_n_t_s.
  318.  
  319.      FFMMTT__OOUUTTPPUUTT__TTOOOO__SSMMAALLLL
  320.           The output buffer was too small to hold  the  converted
  321.           data. This is only returned by FFmmtt__CCoonnvveerrtt.
  322.  
  323.      FFMMTT__IILLLLEEGGAALL__FFOORRMMAATT
  324.           One of the format parameters was illegal.
  325.  
  326.  
  327.  
  328.  
  329. Sprite v.1.0         Printed:  May 29, 1990                     5
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336. Fmt                   C Library Procedures                    Fmt
  337.  
  338.  
  339.  
  340. KKEEYYWWOORRDDSS
  341.      byte-order, byte-swap, alignment, data conversion
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395. Sprite v.1.0         Printed:  May 29, 1990                     6
  396.  
  397.  
  398.  
  399.